Geolocation Functions

Description

Get geolocation information from the browser and store information in the current Grid/UX component object (e.g. if you are in a Grid, the data is stored in the {grid.object}.geoLocation object). (Requires an HTML5 browser). This action can be used to track the user's location over time.

Used with the Grid and UX components. The option 'Get accurate position within a designated radius' can be found the Action JavaScript Geolocation functions. When enabled, you may specify a desired accuracy radius.

The returned lat/lon will fall within the desired accuracy radius if at all possible. This option calls a new custom method that has been added to the navigator.geolocation object called getAccuratePosition(). This method uses the geolocation watchPosition() method to attempt to get position data within a specified accuracy radius. The method will time-out at the maximum wait time and will return the last known location, even if the accuracy does not meet the desired accuracy target.

The maximum wait time defines the maximum amount of time in ms to wait for a geolocation change event. If Ignore first result is checked, the first geolocation point returned will not be used. Some devices return cached location data for the first result, which is, in most cases, inaccurate. The returned geolocation data can be accessed through the {dialog.object}.getGeolocation() method. Example code for the 'Callback function' in the above image:

function gotResults() {
    var e = {dialog.object}.getGeolocation();
    alert('Lat = '+e.latitude+' Lon = '+e.longitude);
 }

Geolocation properties

Set fields to retrieved data: When the Geolocation data is retrieved, one or more fields in the current Component can be updated with Geolocation information.
Property map: Property map property.
Get accurate position within a designated radius: When enabled, multiple requests are made to get position data within a specified radius (in meters). Since each call to retrieve the geolocation is asynchronous, this method can be significantly slower because multiple calls are made to try an obtain a position based on a maximum radius.
Desired accuracy radius (in meters): Defines the accuracy threshold in meters. The location returned will fall within the desired accuracy radius if the function does not timeout. the default value is 20 meters. Choices include 5, 10, 15, 20, 25, 30, 50, 75, 100, 150, 200, 250, 300, 350, 400, 450, 500.
Maximum wait time (ms): Defines the maximum amount of time (in ms) to listen for geolocation change events, default is 10000 (10 secs). Choices include 2500, 5000, 10000, 15000.
Ignore the first result?: Some devices will always return cached location data for the first result. When enabled, the first result will always be ignored.
Update data on location change: Should the Geolocation information be updated when the user's location changes?
Callback function name: (Optional) Specify the name of a JavaScript function to call when the location is initially returned or changes.
Maximum age of cached geolocation object: If the geolocation object is cached, this value establishes a threshold for the maximum allowable age for valid data in milliseconds. The default value is 30 seconds (30000 ms).
Timeout: Sets the timeout threshold that specifies the maximum time allowed (in ms) for the successful retrieval of the geolocation data. Once this threshold is reached, a timeout error alert will display or if using the get accurate position method, a result may be returned that is not within the requested radius. The default value is 15 seconds (15000 ms).